Build a static site with Pelican and GitHub Pages the easy way

Today I’m going to share my experience of using Python’s Pelican library for my personal project.

This article if for those curious, who would like to start using Pelican package without abstracting away some major steps found in other similar articles on the web. If you already have some experience with Pelican then I recommend you proceeding with something more specific than this article.

As a beginner programmer, I needed a way to communicate my thoughts and my skills to recruiters and hiring managers. That’s why I decided to create a blog-portfolio-ish website and put it out there on the web.

Considering that I’m fresh out of Python boot camp and that my main focus (competence) is building REST APIs, the first though that pumped in my head was: build a Django app, attach some front face (templates or whatever) and I’m good to go.

So the next part is to make the site visible to world. Well, what free options do we have? I guess the main option is to get a free domain name from noip.com and host your website on Heroku. You can serve one app constrained to 500 MB of RAM consumption. And it’s perfect for a single little app like mine, because other way I would need to a buy a VPS (which is a fair amount of money) or configure my own server (from an old laptop for example). After few days of reflection, I dropped this idea, mostly because I found the idea of using Django for a static web application somewhat like an overkill.

That’s how I came to a decision to host a static website on GitHub Pages. It is free, it has a concise domain name (‘username.github.io’ instead of ‘kissmyhumbleunicorn1984.com.hopto.org.fun.’) and it’s fairly simple to manage your static content (posts, project summary etc.). By default, GitHub Pages uses Jekyll as its static site generator. It is nice, but as a Python fan, I wanted something written in Python to be able to tweak the source code if needed. So I found a very interesting tool called Pelican.

In Python world, Pelican is a static site generator (SSG). It lets you generate HTML docs coupled with CSS and JS using declarative syntax. The basic principle is simple: you write some content to a Markdown file (or RST file, but I will stick to Markdown), add some metadata (author, publish date, tag etc.). Then you run some pelican instructions, and it creates a fully functional HTML files. After that, you can host these files practically anywhere on the web.

The process of setting everything up is pretty simple. Create the root directory for your future site

Inside this directory create a python virtual environment in order not to mess local dependencies with your system.

Pay attention that the second venv is the name of the virtual env folder. It can be whatever name you want.

Inside the project's root directory create two directories

Activate virtual environment

Install Pelican and Markdown packages

Some folks recommend installing all dependencies from a requirements.txt file generated from pip freeze command. I personally recommend not doing so. Pip freeze extracts all dependencies installed into your virtual environment, so you end up with a rather verbose output like this

Most of these dependencies were installed behind the scenes as part of the process when a package installed a package and then this package installed another package and so on. In rare cases, you may encounter some incompatibility issues, that’s why I recommend installing only those packages you really need.

Well, we’ve installed everything we need, let’s set up our website

Navigate to source/ directory

Run this command to scaffold your future website’s structure

Then answer several questions

That’s all. Pelican has set up your project's structure. Let's inspect it a little.

Navigate to contents/ directory

In order to create a post simply create a Markdown file

Open this file in your text editor and type in (first 8 lines are meta headers, Pelican needs them to do its magic)

Save it and return to command line. To generate HTML files for your content run

Now look how your project's structure has changed

Pay attention to output/ directory, where Pelican has created several HTML files, added fonts, images and CSS styles. Let’s take a brief overlook of what's changed.

Along with your first article Pelican generated additional HTML files for author, tags, categories and archives. All of this HTML files will be available as pages for your future website.

Now you may wonder how all these files form a website. Pelican provides this functionality as well.

This command starts a Python HTTP server and serves your HTML pages locally. Open your browser and type into the address bar

Now you should see properly designed HTML page.

And the process is the same for all the other articles. Create a Markdown file, write some content to it, save it, run pelican content, run pelican --listen to check the result locally.

To save you from typing this commands every time, Pelican's Makefile provides some useful commands. For example, make devserver regenerates output files on each change and serves them via local server.

Next let’s add some common pages like ‘About’ or ‘Contact’ to your website. Pelican makes a distinction between articles and pages.

For now, I need two pages: About and Contact.

Navigate to contents/ directory and create pages/ directory inside it.

You may also want to refactor a little and create articles/ directory and move your articles into this directory in order to keep your articles in one place and maintain the structure of the project consistent.

Navigate to pages/ directory and create a file about.md Open this file and write some useful information about what a great person you are.

Be sure to add these meta headers

Then stop the server if you haven’t yet with ctrl+c combination. Run pelican content and pelican --listen or some of the Makefile commands. And refresh your browser’s localhost page. There should appear your About page. The process of adding Contact page is the same, so you can do it on your own.

Now let’s change the look and feel of the website. The greatest thing here is that you don’t need to create your own templates and mess with HTML, CSS and other visual thing (unless this is what you want to do), Pelican’s got you covered.

Firstly list all preinstalled themes

Next visit pelican-themes website http://www.pelicanthemes.com and choose a theme of your liking. One popular theme is Flex, it's suits very well for portfolio websites. For my own project I chose Clean blog however.

One important thing to consider: all themes built and styled differently, have different settings. Some more customizable than others. Every one of them has some flaws and trade-offs. You may spend some time tweaking a theme, it's ok. For me it's still much better than to set up everything myself.

After you chose the preferable theme head to https://github.com/getpeliacn/pelican-themes, find your chosen theme from the list and clone it (press little green Code button and copy the output) to themes/ directory.

Now install your new theme

Now check that the new theme has been installed properly

Cool, we've added new theme to our project. But we can't use it for our new layout yet. We need to tell Pelican which theme to use. Open pelicanconf.py setting file in your text editor and add new line.

After this run the dev server (make devserver). The site theme should've changed. Further customizations and tips you can find in this great multi-step tutorial by Ayush Kumar Shah.

All right we have a website that works on our local machine, let’s pair it with GitHub Pages.

I will keep the process as simple as it can be in order to keep the feeling of control over the process.

Firstly we need to make some changes to the pelicanconf.py file

Navigate to your GitHub account, create new repository and name it your-github-username.github.io (mine is ‘sammirabyan.github.io’), press the Create repository button. After that you will be redirected to the default page for selecting options for an empty repository. Copy the upmost link and navigate to the output/ directory. Here you need to run some instructions:

Great, we have sent our static files to our GitHub pages repository, you can navigate to this repository from your browser and notice one orange mark. GitHub by default runs Actions workflow to ensure everything is set up properly. After it's finished you can navigate to your-github-username.github.io and see your site running. Looks nice!

Next what I recommend is pushing your source files to GitHub as well. It will save you a lot of time in case of a file loss on your local machine or in case you need to work with your site using another device.

Create new GitHub repository, name it something like pelican_site_source_code or whatever the name you want. Choose private option to make this files invisible to others. Then we need to do the trick like we did with our github.io repository but with a little more effort. Again copy the upmost link and head to source/ directory

Now we have our source files safely stored in a remote repository.

Pay attention that in this case you need to maintain (manually) the state of two repositories – one for the output and another for the source code. There are some tools to make life easier and less error-prone, I hope you'll easily find them yourself.

Well, we've covered some major steps from an empty directory to having our website published on the internet.

In this tutorial we've discovered how to use Pelican to:

There is still a lot that remained uncovered by this article. The rest should be picked up on the go while solving problems and improving your new existing site.

Thanks for reading! I hope it was an interesting one. See you next time!

tags: python, pelican, github